Wi-Fi/BT

Copyright © Quectel Wireless Solutions Co., Ltd. 2026. All rights reserved.

Quectel Pi Debian development board supports Wi-Fi and Bluetooth (BT) connectivity. This document is based on the current on-board environment: the operating system is Debian GNU/Linux 13 (trixie), the wireless network interface is wlan0, the NetworkManager service is active, and commands such as nmcli, wpa_cli, wpa_supplicant and bluetoothctl are available on the board.

💡 It is recommended to use the Debian desktop or nmcli to connect to Wi-Fi. Use wpa_cli / wpa_supplicant only when NetworkManager is unavailable or when low-level debugging or verification of wpa_supplicant behavior is required.

Using the Wi-Fi Function

Method 1: Connect to Wi-Fi from the Debian Desktop

If a MIPI/HDMI display is connected and the Debian GNOME desktop is open, you can connect to a wireless network directly from the desktop network menu. This method is suitable for general functional verification and does not require commands to be entered manually.

  1. Connect a display, mouse, and keyboard, power on the development board, and enter the Debian desktop.

  2. Click the system status area in the upper-right corner of the desktop to expand the network menu.

  3. Ensure that the Wi-Fi switch is on. If it is off, enable Wi-Fi first.

  4. Select the target SSID from the wireless network list.

  5. Enter the Wi-Fi password and confirm the connection.

  6. After the connection is established, access a web page in a browser, or run ip addr show wlan0, ping -c 4 8.8.8.8 in the terminal to verify network connectivity.

Method 3: Connect to Wi-Fi Using wpa_cli / wpa_supplicant (Low-Level Debugging Method)

wpa_supplicant is the low-level Linux component responsible for Wi-Fi authentication and connection, and wpa_cli is its interactive control tool. This method is suitable when NetworkManager is not managing the device and the driver, firmware, or authentication process must be verified. If wlan0 is currently managed by NetworkManager, disconnect it or stop NetworkManager first to prevent two processes from controlling the same wireless network adapter simultaneously.

💡 Before using the wpa_supplicant method, ensure that it will not affect the current remote connection. If the development board relies on Wi-Fi for remote login, stopping NetworkManager may interrupt the network connection.

1. Stop NetworkManager from Managing wlan0 (As Needed)

nmcli device disconnect wlan0
# Alternatively, temporarily stop NetworkManager during debugging
systemctl stop NetworkManager

2. Create the wpa_supplicant Configuration File

wpa_passphrase "SSID_NAME" "Wi-Fi_PASSWORD" > /etc/wpa_supplicant/wpa_supplicant-wlan0.conf

3. Start wpa_supplicant

ip link set wlan0 up
wpa_supplicant -B -i wlan0 -c /etc/wpa_supplicant/wpa_supplicant-wlan0.conf

4. Obtain an IP Address Through DHCP

dhclient wlan0
# If dhclient is not installed, use udhcpc or NetworkManager to obtain an address as appropriate for the system

5. Check the Connection Status Using wpa_cli

wpa_cli -i wlan0 status
wpa_cli -i wlan0 scan
wpa_cli -i wlan0 scan_results

When wpa_state=COMPLETED and ip_address contains a valid address, Wi-Fi authentication and IP address acquisition are functioning properly.

6. Connect Interactively Using wpa_cli (Optional)

wpa_cli -i wlan0
> scan
> scan_results
> add_network
> set_network 0 ssid "\"SSID_NAME\""
> set_network 0 psk "\"Wi-Fi_PASSWORD\""
> enable_network 0
> save_config
> status

Using the Bluetooth Function

Quectel Pi Debian development board has built-in Bluetooth functionality. The on-board bluetooth service is currently active, and bluetoothctl show can detect the controller, indicating that the basic Bluetooth service has started.

Method 1: Connect to a Bluetooth Device from the Debian Desktop

  1. After entering the Debian desktop, open Settings.

  2. Open the Bluetooth page.

  3. Turn on Bluetooth and set the target Bluetooth device to pairing/discoverable mode.

  4. Select the target device from the device list, such as a Bluetooth headset, keyboard, or mouse.

  5. Follow the on-screen prompts to complete Pair and Connect.

Method 2: Connect to a Bluetooth Device Using bluetoothctl

If no graphical interface is available, or debugging through ADB or a serial port is required, use bluetoothctl.

systemctl status bluetooth
bluetoothctl

After entering bluetoothctl, run:

power on
agent on
default-agent
scan on

After the target device is discovered, record its MAC address, and then run:

pair XX:XX:XX:XX:XX:XX
trust XX:XX:XX:XX:XX:XX
connect XX:XX:XX:XX:XX:XX
scan off
quit

After connecting, use the following commands to check the controller and device status:

bluetoothctl show
bluetoothctl devices
bluetoothctl info XX:XX:XX:XX:XX:XX

Troubleshooting

Symptom

Troubleshooting Method

No Wi-Fi Networks Are Found

Check the antenna connection, run rfkill list to check whether Wi-Fi is soft-blocked or hard-blocked, run nmcli radio wifi on, and then scan again.

wlan0 Does Not Exist

Run ip link, dmesg | grep -i wlan to check whether the driver and firmware are loaded.

nmcli Connection Fails

Check whether the SSID and password are correct, and use journalctl -u NetworkManager -b to view the NetworkManager logs.

wpa_cli Indicates That It Cannot Connect

Ensure that wpa_supplicant has started and that its control interface matches the interface used by wpa_cli -i wlan0.

Bluetooth Cannot Discover Devices

Ensure that systemctl status bluetooth is functioning properly, run bluetoothctl power on, and ensure that the peripheral is in discoverable mode.

On-Board Verification Commands

During maintenance or troubleshooting, first collect the following information to verify the system, interface, and service status:

cat /etc/os-release
uname -a
ip link show wlan0
nmcli general status
nmcli device status
systemctl is-active NetworkManager
systemctl is-active bluetooth
bluetoothctl show